feat(agc): capture GPU atomic image inputs before selected dispatches - #3

What

A selected compute dispatch can stall after earlier GPU writes changed an atomic image, while a CPU-side shader request capture cannot show that input. Add an opt-in, bounded readback immediately before the selected prepared dispatch so its actual atomic image contents can be inspected alongside the final prepared SPIR-V and patched push constants.

APS5_DUMP_ATOMIC_INPUT selects a hexadecimal program address. APS5_DUMP_ATOMIC_INPUT_DIR selects the output directory and APS5_DUMP_ATOMIC_INPUT_LIMIT sets a count from 1 to 64 (default 8). Captures are limited to 16 MiB per image and 64 MiB per session. Packed image data and metadata include format, mip, layers, dimensions, storage element and dispatch variants. When GPU timing is enabled, the log correlates the following dispatch with its exact submission batch and timing range.

The capture submits and waits for preceding work, then reads the image through a staging buffer and restores its GENERAL layout. It changes diagnostic timing and is unsuitable for performance comparisons. Default operation performs no capture readbacks. File errors stop capturing; GPU errors still propagate. Metadata is written last as the successful capture marker.

This captures atomic images only. Guest buffers, sampled textures and resolved GPU-indirect argument values are not captured. Normal resource preparation and completion actions can publish earlier GPU results; the capture does not write its copied bytes back to guest memory.

Related investigation: #1. This is diagnostic infrastructure, not a fix for that stall. Outputs can contain proprietary shader data and must remain private. The open upstream gated-dispatch capture PR boykopovar#1864 concerns when guest requests are resolved; it does not implement this GPU atomic image readback.

Tested

Windows 11, GCC 15.2 MinGW, RTX 5070, NVIDIA 617.42:

• Built this branch on upstream main 6cc0503.
• ctest -R '^agc_driver_gpu_atomic_input$' passed in 0.40 s.
• The synthetic wave64 test checks capture of preceding queued atomic writes (19 and 21), packed image bytes, count limits, unmatched programs, invalid settings, final counter 25 and all 64 output lanes. Devices without guest memory import report CTest skip rather than a false failure.
• On the local integration build, six focused capture, recorder, image atomic and wave ticket tests passed in 1.34 s before extraction to this branch.
• Convention checks and whitespace checks pass.
• ASTRO BOT on integration81bd5f16 produced eight real GPU atomic image snapshots with the final prepared shader and patched push constants. The same dispatch stalled after the eight-capture limit and the run ended in device loss. See issue ASTRO BOT: reproducible GPU device loss during title transition on RTX 5070 #1 for sanitized measurements. No stall fix, gameplay or FPS improvement is claimed.

Checklist

• Based on current main; checked open upstream PRs for overlapping capture work
• One topic per PR
• No added code comments
• No game data, logs, screenshots or investigation documents committed
• No new third-party code
• Generic diagnostic behavior
• Depends on: none
• AI-assisted: yes (Codex); reviewed and tested locally